@Nazarevsky Thanks for the PR! Since this is your first contribution, I’m being a bit more nitpicky about commit structure. Even if this one doesn’t end up being merged for the reason below, this review should be useful as a reference for future PRs.

That said, I wanted to better understand whether this PR serves its intended purpose. Don’t the existing invoice.description and fetchinvoice.payer_note already cover this use case? A node can already inspect these via listinvoices. How is the payer_note sent via xpay received on the other node? Adding @Lagrang3 in case I’ve missed anything.

Thank you @ShahanaFarooqui for comments!

I've updated my PR description a bit about my changes. Nevertheless, I'd like to answer your questions here.

I think that invoice.description is a bit different because it provides a message to a payer. Basically, I'd say that it is rather an invoice description then payment description unlike payer_note. As you mentioned, fetchinvoice.payer_note is indeed exists and a corresponding logic for sending payer_note is implemented. However, no corresponding field in xpay for sending custom messages provided.

I think that invoice.description is a bit different because it provides a message to a payer. Basically, I'd say that it is rather an invoice description then payment description unlike payer_note. As you mentioned, fetchinvoice.payer_note is indeed exists and a corresponding logic for sending payer_note is implemented. However, no corresponding field in xpay for sending custom messages provided.

Why a sender cannot attach an arbitrary description to a Lightning payment:

BOLT 4 (Onion Routing Protocol) defines the Lightning payment routing layer and specifies exactly what data is carried hop-by-hop in a payment.

According to BOLT 4:

• Onion payloads carry routing and settlement data only, such as: amounts, CLTV expiry values, channel identifiers, defined TLV records required for forwarding
• A payment is identified solely by the payment hash/preimage
• There is no field for a free-form sender description or payer note
  As a result, the sender cannot arbitrarily attach descriptive metadata at the routing or payment layer.

By contrast, descriptions are defined only at the invoice layer:

BOLT 11 invoices include a d (description) or h (description hash) field, set by the invoice creator (receiver)
BOLT 12 similarly defines descriptions as part of offers/invoices (again receiver-defined)

Summary

• The Lightning protocol does not support it
• Lightning allows descriptions only in invoices (bolt11/botl12), which are created by the receiver.
• The routing and payment protocol (BOLT 4) provides no mechanism for a sender to attach an independent description to a payment.

Thank you for referencing, it makes much more sense to me now 👍

Thanks for the PR @Nazarevsky, I may be missing the purpose of it. There are plenty of places in both CLN and the spec where a description of some sort is mentioned.

As far as I see we only have XXX times that a description leaves one node and ends up at another node:

• fetchinvoice where the payer_note, which I think, which is handled by the offers plugin. During the negotiation for a BOLT12 invoice, the prospective sender sends the recipient some metadata, to retrieve the invoice, and passing a note along. This is not saved as far as I see. This is not equivalent to calling xpay since it happens during the negotiation of the invoice, not the payment attempt of the invoice.
• create_invoice is purely local, and the description is added to the invoice being returned, and not saved. Since there is no communication involved this is not comparable.
• As part of the invoice we also pass a description along in the invoice, as an encoded base58 string.

I'm not against sending an optional message along with the payment, however notice that the spec does not have a field to transport this message, and the recipient has no handling / storing of any received message. If we want to go down this road, we should at least remember the messages we get ourselves first :-)

Anyway, as mentioned, I may be completely off, so please share your intent and we can work off of that ^^

EDIT: reading the OP again, it seems clear that there is a bit of confusion what the scope is. BOLT11 is the payment descriptor in the form of an invoice, i.e., they are the payment instructions sent from recipient to the sender on how to get back to it.

BOLT12 takes a step back, we don't have an invoice yet, we need to negotiate one. The prospective sender, given the recipient ID, talks to it, providing all the details for the payment it intends to perform. The recipient takes that information and returns an invoice.

So BOLT12 tells you how to get an invoice, BOLT11 tells you what is in the invoice, and xpay, renepay and pay take an invoice and execute the payment.

Thank you for joining @cdecker!

so please share your intent and we can work off of that

Basically, my intent was to provide some custom message using xpay command. As it was mentioned, it is not possible to do it by providing along with a payment directly, so I decided to do it by payer_note field in fetchinvoice RPC call (according to Bolt12 specification, type 89).

Current implementation already has payer_note field in fetchinvoice RPC call. On the other side even though xpay leverages fetchinvoice, xpay has no logic for providing a custom message even on an invoice later, so adding this field to the JSON request did all the work.

If we want to go down this road, we should at least remember the messages we get ourselves first

I also think so. listinvoices shows us payer_note for BOLT12 invoices so I decided to not add any other methods for that. Do you think that we need the other approach for getting messages?

So BOLT12 tells you how to get an invoice, BOLT11 tells you what is in the invoice, and xpay, renepay and pay take an invoice and execute the payment.

Yes, since there is no way to provide payment description when paying BOLT11 invoices, I decided to leave it as it is.

My bad, I totally blanked on the fact that xpay does use fetchinvoice to actually execute BOLT12, which does have the payer_note, and it is already being handled correctly by the offers plugin. Apologies for not realizing my mistake earlier, your PR makes absolute sense now.

I think this is good as is, and can be merged 👍